<HTML>
<HEAD>
<TITLE>XML::LibXML::Document - DOM Document Class</TITLE>
<LINK REV="made" HREF="mailto:root@updates.mandrakesoft.com">
</HEAD>

<BODY>

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<UL>

		<LI><A HREF="#Methods">Methods</A>
	</UL>

	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
	<LI><A HREF="#VERSION">VERSION</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<H1><A NAME="NAME">NAME</A></H1>
<P>
XML::LibXML::Document - DOM Document Class

<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<P>
<PRE>  use XML::LibXML::Document;
</PRE>
<P>
<PRE>  $dom = XML::LibXML::Document-&gt;new( $version, $encoding );
  $dom = XML::LibXML::Document-&gt;createDocument( $version, $encoding );
  $strEncoding = $doc-&gt;getEncoding();
  $strVersion = $doc-&gt;getVersion();
  $docstring = $dom-&gt;toString([$format]);
  $bool = $dom-&gt;is_valid();
  $root = $dom-&gt;getDocumentElement($name, $namespace );
  $dom-&gt;setDocumentElement( $root );
  $element = $dom-&gt;createElement( $nodename );
  $element = $dom-&gt;createElementNS( $namespaceURI, $qname );
  $text = $dom-&gt;createTextNode( $content_text );
  $comment = $dom-&gt;createComment( $comment_text );
  $attrnode = $doc-&gt;createAttribute($name [,$value]);
  $attrnode = $doc-&gt;createAttributeNS( namespaceURI, $name [,$value] );
  $cdata = $dom-&gt;create( $cdata_content );
  $document-&gt;importNode( $node [, $move] );
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
The Document Class is the result of a parsing process. But sometimes it is
necessary to create a Document from scratch. The DOM Document Class
provides functions that are conform to the DOM Core naming style. It
inherits all functions from <EM>XML::LibXML::Node</EM> as specified in DOM Level2. This enables to access the nodes beside the
root element on document level - a <EM>DTD</EM> for example. The support for these nodes is limited at the moment, so I
would recommend, not to use <EM>node</EM> functions on <EM>documents</EM>. It is suggested that one should always create a node not bound to any
document. There is no need of really including the node to the document,
but once the node is bound to a document, it is quite safe that all strings
have the correct encoding. If an unbound textnode with an iso encoded
string is created (e.g. with $CLASS-&gt;new()), the <EM>toString</EM> function may not return the expected result. This seems like a limitation
as long UTF8 encoding is assured. If iso encoded strings come into play it
is much safer to use the node creation functions of <STRONG>XML::LibXML::Document</STRONG>.

<P>
<HR>
<H2><A NAME="Methods">Methods</A></H2>
<DL>
<DT><STRONG><A NAME="item_new">new</A></STRONG><DD>
<P>
alias for <CODE>createDocument()</CODE>

<DT><STRONG><A NAME="item_createDocument">createDocument</A></STRONG><DD>
<P>
The constructor for the document class. As Parameter it takes the version
string and (optionally) the ecoding string. Simply calling <STRONG>createDocument</STRONG> will create the document:

<P>
<PRE>  
  &lt;?xml version=&quot;your version&quot; encoding=&quot;your encoding&quot;?&gt;
</PRE>
<P>
Both parameter are optional. The default value for <STRONG>$version</STRONG> is <EM>1.0</EM> , of course. If the <STRONG>$encoding</STRONG> parameter is not set, the encoding will be left unset, which means UTF8 is
implied (and set). The call of <STRONG>createDocument</STRONG> without any parameter will result the following code:

<P>
<PRE>  
  &lt;?xml version=&quot;1.0&quot;?&gt;
</PRE>
<DT><STRONG><A NAME="item_getEncoding">getEncoding</A></STRONG><DD>
<P>
returns the encoding string of the document

<DT><STRONG><A NAME="item_getVersion">getVersion</A></STRONG><DD>
<P>
returns the version string of the document

<DT><STRONG><A NAME="item_toString">toString</A></STRONG><DD>
<P>
<STRONG>toString</STRONG> is a deparsing function, so the DOM Tree can be translated into a string,
ready for output. The optional <STRONG>$format</STRONG> parameter sets the indenting of the output. This parameter is expected to
be an <EM>integer</EM> value, that specifies the number of linebreaks for each node. For more
information about the formatted output check the documentation of <EM>xmlDocDumpFormatMemory</EM> in <EM>libxml2/tree.h</EM> .

<DT><STRONG><A NAME="item_is_valid">is_valid</A></STRONG><DD>
<P>
Returns either TRUE or FALSE depending on the DOM Tree is a valid Document
or not.

<DT><STRONG><A NAME="item_getDocumentElement">getDocumentElement</A></STRONG><DD>
<P>
Returns the root element of the Document. A document can have just one root
element to contain the documents data.

<DT><STRONG><A NAME="item_setDocumentElement">setDocumentElement</A></STRONG><DD>
<P>
This function enables you to set the root element for a document. The
function supports the import of a node from a different document tree.

<DT><STRONG><A NAME="item_createElement">createElement</A></STRONG><DD>
<P>
This function creates a new Element Node bound to the DOM with the name <EM>$nodename</EM> .

<DT><STRONG><A NAME="item_createElementNS">createElementNS</A></STRONG><DD>
<P>
This function creates a new Element Node bound to the DOM with the name <EM>$nodename</EM> and placed in the given namespace.

<DT><STRONG><A NAME="item_createTextNode">createTextNode</A></STRONG><DD>
<P>
As an equivalent of <STRONG>createElement</STRONG> , but it creates a <STRONG>Text Node</STRONG> bound to the DOM.

<DT><STRONG><A NAME="item_createComment">createComment</A></STRONG><DD>
<P>
As an equivalent of <STRONG>createElement</STRONG> , but it creates a <STRONG>Comment Node</STRONG> bound to the DOM.

<DT><STRONG><A NAME="item_createAttribute">createAttribute</A></STRONG><DD>
<P>
Creates a new Attribute node. This function is rather useless at the
moment, since there is no setAttributeNode function defined in <EM>XML::LibXML::Element</EM> , yet.

<DT><STRONG><A NAME="item_createAttributeNS">createAttributeNS</A></STRONG><DD>
<P>
Creates an Attribute bound to a namespace.

<DT><STRONG><A NAME="item_createCDATASection">createCDATASection</A></STRONG><DD>
<P>
Similar to createTextNode and createComment, this function creates a
CDataSection bound to the current DOM.

<DT><STRONG><A NAME="item_importNode">importNode</A></STRONG><DD>
<P>
If a node is not part of a document, it can be imported to another
document. As specified in DOM Level 2 Specification the Node will not be
altered or removed from its original document by default. ( <EM>$node-</EM><CODE>cloneNode(1)&gt;</CODE> will get called implicitly). Sometimes it is
necessary to <EM>move</EM> a node between documents. In such a case the node will not be copied, but
removed from the original document.

</DL>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
XML::LibXML, XML::LibXML::Element, XML::LibXML::Text, XML::LibXML::Attr,
XML::LibXML::Comment

<P>
<HR>
<H1><A NAME="VERSION">VERSION</A></H1>
<P>
0.90_a

</BODY>

</HTML>
